home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / perl / 5.10.0 / CPANPLUS / Backend / RV.pm
Encoding:
Perl POD Document  |  2009-06-26  |  3.7 KB  |  145 lines
  1. package CPANPLUS::Backend::RV;
  2.  
  3. use strict;
  4. use vars qw[$STRUCT];
  5.  
  6.  
  7. use CPANPLUS::Error;
  8. use CPANPLUS::Internals::Constants;
  9.  
  10. use IPC::Cmd                    qw[can_run run];
  11. use Params::Check               qw[check];
  12.  
  13. use base 'Object::Accessor';
  14.  
  15. local $Params::Check::VERBOSE = 1;
  16.  
  17.  
  18. =pod
  19.  
  20. =head1 NAME
  21.  
  22. CPANPLUS::Backend::RV
  23.  
  24. =head1 SYNOPSIS
  25.  
  26.     ### create a CPANPLUS::Backend::RV object
  27.     $backend_rv     = CPANPLUS::Backend::RV->new(
  28.                                 ok          => $boolean,
  29.                                 args        => $args,
  30.                                 rv          => $return_value
  31.                                 function    => $calling_function );
  32.  
  33.     ### if you have a CPANPLUS::Backend::RV object
  34.     $passed_args    = $backend_rv->args;    # args passed to function
  35.     $ok             = $backend_rv->ok;      # boolean indication overall
  36.                                             # result of the call
  37.     $function       = $backend_rv->fucntion # name of the calling
  38.                                             # function
  39.     $rv             = $backend_rv->rv       # the actual return value
  40.                                             # of the calling function
  41.  
  42. =head1 DESCRIPTION
  43.  
  44. This module provides return value objects for multi-module
  45. calls to CPANPLUS::Backend. In boolean context, it returns the status
  46. of the overall result (ie, the same as the C<ok> method would).
  47.  
  48. =head1 METHODS
  49.  
  50. =head2 new( ok => BOOL, args => DATA, rv => DATA, [function => $method_name] )
  51.  
  52. Creates a new CPANPLUS::Backend::RV object from the data provided.
  53. This method should only be called by CPANPLUS::Backend functions.
  54. The accessors may be used by users inspecting an RV object.
  55.  
  56. All the argument names can be used as accessors later to retrieve the
  57. data.
  58.  
  59. Arguments:
  60.  
  61. =over 4
  62.  
  63. =item ok
  64.  
  65. Boolean indicating overall success
  66.  
  67. =item args
  68.  
  69. The arguments provided to the function that returned this rv object.
  70. Useful to inspect later to see what was actually passed to the function
  71. in case of an error.
  72.  
  73. =item rv
  74.  
  75. An arbitrary data structure that has the detailed return values of each
  76. of your multi-module calls.
  77.  
  78. =item function
  79.  
  80. The name of the function that created this rv object.
  81. Can be explicitly passed. If not, C<new()> will try to deduce the name
  82. from C<caller()> information.
  83.  
  84. =back
  85.  
  86. =cut
  87.  
  88. sub new {
  89.     my $class   = shift;
  90.     my %hash    = @_;
  91.  
  92.     my $tmpl = {
  93.         ok          => { required => 1, allow => BOOLEANS },
  94.         args        => { required => 1 },
  95.         rv          => { required => 1 },
  96.         function    => { default => CALLING_FUNCTION->() },
  97.     };
  98.  
  99.     my $args    = check( $tmpl, \%hash ) or return;
  100.     my $self    = bless {}, $class;
  101.  
  102. #    $self->mk_accessors( qw[ok args function rv] );
  103.     $self->mk_accessors( keys %$tmpl );
  104.  
  105.     ### set the values passed in the struct ###
  106.     while( my($key,$val) = each %$args ) {
  107.         $self->$key( $val );
  108.     }
  109.  
  110.     return $self;
  111. }
  112.  
  113. sub _ok { return shift->ok }
  114. #sub _stringify  { Carp::carp( "stringifying!" ); overload::StrVal( shift ) }
  115.  
  116. ### make it easier to check if($rv) { foo() }
  117. ### this allows people to not have to explicitly say
  118. ### if( $rv->ok ) { foo() }
  119. ### XXX add an explicit stringify, so it doesn't fall back to "bool"? :(
  120. use overload bool       => \&_ok, 
  121. #             '""'       => \&_stringify,
  122.              fallback   => 1;
  123.  
  124. =pod
  125.  
  126. =head1 BUG REPORTS
  127.  
  128. Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>.
  129.  
  130. =head1 AUTHOR
  131.  
  132. This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
  133.  
  134. =head1 COPYRIGHT
  135.  
  136. The CPAN++ interface (of which this module is a part of) is copyright (c) 
  137. 2001 - 2007, Jos Boumans E<lt>kane@cpan.orgE<gt>. All rights reserved.
  138.  
  139. This library is free software; you may redistribute and/or modify it 
  140. under the same terms as Perl itself.
  141.  
  142. =cut
  143.  
  144. 1;
  145.